توزيع حزم بايثون: النشر على PyPI وإدارة الإصدارات

يعتمد النظام البيئي الواسع لبايثون على مجموعة ضخمة من الحزم المتاحة بسهولة من خلال مؤشر حزم بايثون (PyPI). يقدم هذا الدليل نظرة شاملة حول كيفية توزيع حزم بايثون الخاصة بك عبر PyPI، مما يضمن إتاحتها للمطورين في جميع أنحاء العالم. سنستكشف الأدوات الأساسية وأفضل الممارسات لإدارة الإصدارات وسير العمل لإنشاء ونشر حزم بايثون عالية الجودة.

لماذا توزع حزمة بايثون الخاصة بك؟

يوفر توزيع حزمة بايثون الخاصة بك العديد من الفوائد:

• مشاركة عملك: يسمح للمطورين الآخرين بإعادة استخدام الكود الخاص بك بسهولة، مما يعزز التعاون والابتكار. تخيل فريقًا عالميًا يستخدم أدوات تحليل البيانات المتخصصة التي بنيتها في بايثون.
• إدارة التبعيات: يبسط عملية إدارة التبعيات في المشاريع الأخرى. يمكن تثبيت حزمتك بأمر واحد، جنبًا إلى جنب مع جميع تبعياتها.
• المساهمة في المصدر المفتوح: يمكّنك من المساهمة في مجتمع المصدر المفتوح والحصول على تقدير لعملك. العديد من مكونات البرامج الهامة هي حزم مفتوحة المصدر يحتفظ بها مطورون في جميع أنحاء العالم.
• التحكم في الإصدارات والتحديثات: يوفر طريقة منظمة لإدارة الإصدارات وإصدار التحديثات ومعالجة إصلاحات الأخطاء. وهذا يضمن أن المستخدمين لديهم دائمًا إمكانية الوصول إلى أحدث إصدار وأكثرها موثوقية من حزمتك.
• سهولة التثبيت: يبسط التثبيت للمستخدمين من خلال `pip install your-package-name`.

الأدوات الأساسية لتوزيع حزم بايثون

هناك العديد من الأدوات الضرورية لإنشاء وتوزيع حزم بايثون:

• setuptools: مكتبة مستخدمة على نطاق واسع لتحديد البيانات الوصفية للحزمة، بما في ذلك الاسم والإصدار والتبعيات ونقاط الدخول. وهي المعيار الفعلي لتغليف مشاريع بايثون.
• wheel: تنسيق توزيع يوفر عملية تثبيت أكثر كفاءة وموثوقية مقارنة بتوزيعات المصدر. الـ Wheels هي توزيعات مبنية مسبقًا يمكن تثبيتها دون الحاجة إلى الترجمة.
• twine: أداة لرفع حزمتك بأمان إلى PyPI. يقوم Twine بتشفير بيانات الاعتماد وبيانات الحزمة أثناء الإرسال، مما يحمي من التنصت وهجمات "رجل في المنتصف".
• venv/virtualenv: هذه أدوات لإنشاء بيئات بايثون معزولة. يعد استخدام البيئات الافتراضية أمرًا بالغ الأهمية لإدارة التبعيات وتجنب التعارض بين المشاريع المختلفة.

إعداد مشروعك

قبل أن تتمكن من توزيع حزمتك، تحتاج إلى هيكلة مشروعك بشكل صحيح.

مثال على هيكل المشروع

my_package/
├── my_package/
│   ├── __init__.py
│   ├── module1.py
│   └── module2.py
├── tests/
│   ├── __init__.py
│   ├── test_module1.py
│   └── test_module2.py
├── README.md
├── LICENSE
├── setup.py
└── .gitignore

شرح:

• my_package/: الدليل الرئيسي الذي يحتوي على الكود المصدري لحزمتك.
• my_package/__init__.py: يجعل دليل `my_package` حزمة بايثون. يمكن أن يكون فارغًا أو يحتوي على كود تهيئة.
• my_package/module1.py, my_package/module2.py: وحدات بايثون الخاصة بك التي تحتوي على الكود الفعلي.
• tests/: دليل يحتوي على اختبارات الوحدة الخاصة بك. من الضروري كتابة اختبارات لضمان جودة وموثوقية حزمتك.
• README.md: ملف Markdown يقدم وصفًا لحزمتك وتعليمات الاستخدام ومعلومات أخرى ذات صلة. غالبًا ما يكون هذا أول ما يراه المستخدمون على PyPI.
• LICENSE: ملف يحتوي على الترخيص الذي يتم توزيع حزمتك بموجبه (على سبيل المثال، MIT، Apache 2.0، GPL). يعد اختيار الترخيص المناسب أمرًا ضروريًا لتحديد كيفية استخدام الآخرين للكود الخاص بك.
• setup.py: ملف التكوين الرئيسي الذي يحدد البيانات الوصفية لحزمتك وتعليمات البناء.
• .gitignore: يحدد الملفات والأدلة التي يجب أن يتجاهلها Git (على سبيل المثال، الملفات المؤقتة، ومخرجات البناء).

إنشاء ملف `setup.py`

ملف `setup.py` هو قلب توزيع حزمتك. يحتوي على بيانات وصفية حول حزمتك وتعليمات لبنائها وتثبيتها. إليك مثال:

import setuptools

with open("README.md", "r") as fh:
    long_description = fh.read()

setuptools.setup(
    name="my_package",  # استبدل باسم حزمتك
    version="0.1.0",
    author="اسمك",  # استبدل باسمك
    author_email="your.email@example.com", # استبدل ببريدك الإلكتروني
    description="حزمة مثال صغيرة",
    long_description=long_description,
    long_description_content_type="text/markdown",
    url="https://github.com/yourusername/my_package", # استبدل بعنوان URL لمستودعك
    packages=setuptools.find_packages(),
    classifiers=[
        "Programming Language :: Python :: 3",
        "License :: OSI Approved :: MIT License",
        "Operating System :: OS Independent",
    ],
    python_requires='>=3.6',
    install_requires=[
        "requests", # تبعية مثال
    ],
)

شرح:

• name: اسم حزمتك، والذي سيتم استخدامه على PyPI. اختر اسمًا فريدًا ووصفيًا.
• version: رقم إصدار حزمتك. اتبع الإصدار الدلالي (انظر أدناه).
• author, author_email: اسمك وعنوان بريدك الإلكتروني.
• description: وصف قصير لحزمتك.
• long_description: وصف أطول وأكثر تفصيلاً، يُقرأ عادةً من ملف `README.md` الخاص بك.
• long_description_content_type: يحدد تنسيق الوصف الطويل الخاص بك (على سبيل المثال، "text/markdown").
• url: عنوان URL للصفحة الرئيسية لحزمتك (على سبيل المثال، مستودع GitHub).
• packages: قائمة بالحزم التي سيتم تضمينها في توزيعك. يقوم `setuptools.find_packages()` تلقائيًا باكتشاف جميع الحزم في مشروعك.
• classifiers: بيانات وصفية تساعد المستخدمين في العثور على حزمتك على PyPI. اختر مصنفات مناسبة من قائمة مصنفات Trove. ضع في اعتبارك تضمين مصنفات لإصدارات بايثون المدعومة وأنظمة التشغيل والتراخيص.
• python_requires: يحدد الحد الأدنى من إصدار بايثون المطلوب لاستخدام حزمتك.
• install_requires: قائمة بالتبعيات التي تتطلبها حزمتك. سيتم تثبيت هذه التبعيات تلقائيًا عند تثبيت حزمتك.

إدارة الإصدارات: الإصدار الدلالي

الإصدار الدلالي (SemVer) هو نظام إصدارات معتمد على نطاق واسع يوفر طريقة واضحة ومتسقة لتوصيل طبيعة التغييرات في حزمتك.

يتكون رقم إصدار SemVer من ثلاثة أجزاء: MAJOR.MINOR.PATCH.

• MAJOR (الرئيسي): يتم زيادته عند إجراء تغييرات غير متوافقة في واجهة برمجة التطبيقات (API). يشير هذا إلى تغيير كبير قد يتطلب من المستخدمين تحديث أكوادهم.
• MINOR (الفرعي): يتم زيادته عند إضافة وظائف بطريقة متوافقة مع الإصدارات السابقة. وهذا يعني ميزات أو تحسينات جديدة لا تكسر الكود الحالي.
• PATCH (التصحيح): يتم زيادته عند إجراء إصلاحات أخطاء متوافقة مع الإصدارات السابقة. هذا مخصص للإصلاحات الصغيرة التي لا تضيف ميزات جديدة أو تكسر الوظائف الحالية.

أمثلة:

• 1.0.0: الإصدار الأولي.
• 1.1.0: تمت إضافة ميزة جديدة دون كسر الكود الحالي.
• 1.0.1: تم إصلاح خطأ في إصدار 1.0.0.
• 2.0.0: تم إجراء تغييرات غير متوافقة في واجهة برمجة التطبيقات (API).

يساعد استخدام SemVer المستخدمين على فهم تأثير الترقية إلى إصدار جديد من حزمتك.

بناء حزمتك

بمجرد تكوين ملف `setup.py` الخاص بك، يمكنك بناء حزمتك.

1. إنشاء بيئة افتراضية: يوصى بشدة بإنشاء بيئة افتراضية لعزل تبعيات حزمتك. استخدم `python3 -m venv .venv` (أو `virtualenv .venv`) ثم قم بتنشيطها (`source .venv/bin/activate` على Linux/macOS، و `.venv\Scripts\activate` على Windows).
2. تثبيت تبعيات البناء: قم بتشغيل `pip install --upgrade setuptools wheel`.
3. بناء الحزمة: قم بتشغيل `python setup.py sdist bdist_wheel`. ينشئ هذا الأمر ملفي توزيع في دليل `dist`: توزيع المصدر (sdist) وتوزيع wheel (bdist_wheel).

يحتوي `sdist` على الكود المصدري وملف `setup.py`. أما `bdist_wheel` فهو توزيع مبني مسبقًا يمكن تثبيته بسرعة أكبر.

نشر حزمتك على PyPI

قبل أن تتمكن من نشر حزمتك، تحتاج إلى إنشاء حساب على PyPI (https://pypi.org/) وإنشاء رمز API. سيتم استخدام هذا الرمز لمصادقة عمليات الرفع الخاصة بك.

1. التسجيل على PyPI: اذهب إلى https://pypi.org/account/register/ وأنشئ حسابًا.
2. إنشاء رمز API: اذهب إلى https://pypi.org/manage/account/، انتقل لأسفل إلى قسم "API tokens"، وأنشئ رمزًا جديدًا. قم بتخزين هذا الرمز بأمان، حيث ستحتاج إليه لرفع حزمتك.
3. تثبيت Twine: قم بتشغيل `pip install twine`.
4. رفع حزمتك: قم بتشغيل `twine upload dist/*`. سيُطلب منك اسم المستخدم (__token__) وكلمة المرور (رمز API الذي أنشأته).

ملاحظة أمنية هامة: لا تقم أبدًا بتضمين رمز API الخاص بك في المستودع. قم بتخزينه بأمان واستخدم متغيرات البيئة أو طرق آمنة أخرى للوصول إليه أثناء عملية الرفع.

اختبار تثبيت حزمتك

بعد نشر حزمتك، من الضروري اختبار إمكانية تثبيتها بشكل صحيح.

1. إنشاء بيئة افتراضية جديدة: هذا يضمن أنك تختبر التثبيت في بيئة نظيفة.
2. تثبيت حزمتك: قم بتشغيل `pip install your-package-name`.
3. استيراد واستخدام حزمتك: في مفسر بايثون، قم باستيراد حزمتك وتحقق من أنها تعمل كما هو متوقع.

التكامل المستمر والنشر المستمر (CI/CD)

لأتمتة عملية بناء واختبار ونشر حزمتك، يمكنك استخدام أدوات CI/CD مثل GitHub Actions أو GitLab CI أو Travis CI.

إليك مثال على سير عمل GitHub Actions يقوم ببناء ونشر حزمتك على PyPI:

name: النشر على PyPI

on:
  release:
    types: [published]

jobs:
  publish:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v2
    - name: إعداد بايثون 3.x
      uses: actions/setup-python@v2
      with:
        python-version: 3.x
    - name: تثبيت التبعيات
      run: |
        python -m pip install --upgrade pip
        pip install setuptools wheel twine
    - name: بناء الحزمة
      run: python setup.py sdist bdist_wheel
    - name: نشر الحزمة على PyPI
      run: |
        twine upload dist/* \
          -u __token__ \
          -p ${{ secrets.PYPI_API_TOKEN }}

شرح:

• يتم تشغيل سير العمل هذا عند نشر إصدار جديد على GitHub.
• يقوم بسحب الكود، وإعداد بايثون، وتثبيت التبعيات، وبناء الحزمة، ورفعها إلى PyPI.
• secrets.PYPI_API_TOKEN هو سر من أسرار GitHub يخزن رمز API الخاص بـ PyPI. تحتاج إلى تكوين هذا السر في إعدادات مستودع GitHub الخاص بك.

أفضل الممارسات لتوزيع حزم بايثون

• كتابة وثائق شاملة: قم بتضمين ملف `README.md` مفصل، بالإضافة إلى وثائق واجهة برمجة التطبيقات (API) باستخدام أدوات مثل Sphinx. الوثائق الواضحة والكاملة ضرورية لجعل حزمتك سهلة الاستخدام.
• كتابة اختبارات الوحدة: اختبر الكود الخاص بك بدقة لضمان جودته وموثوقيته. استخدم إطار عمل اختبار مثل pytest أو unittest.
• اتبع إرشادات أسلوب PEP 8: التزم بدليل أسلوب اقتراح تحسين بايثون 8 (PEP 8) لضمان كود متسق وقابل للقراءة.
• استخدم ترخيصًا: اختر ترخيصًا مفتوح المصدر مناسبًا لتحديد كيفية استخدام الآخرين للكود الخاص بك.
• حافظ على تحديث تبعياتك: قم بتحديث تبعيات حزمتك بانتظام للاستفادة من إصلاحات الأخطاء والتصحيحات الأمنية والميزات الجديدة.
• استخدم بيئة افتراضية: قم دائمًا بتطوير واختبار حزمتك داخل بيئة افتراضية لعزل التبعيات.
• ضع في اعتبارك التدويل (i18n) والتعريب (l10n): إذا كانت حزمتك تتعامل مع نصوص أو بيانات موجهة للمستخدم، ففكر في جعلها قابلة للتكيف مع لغات ومناطق مختلفة. هذا يوسع قاعدة المستخدمين المحتملين على مستوى العالم. يمكن لأدوات مثل Babel المساعدة في ذلك.
• تعامل مع مناطق زمنية وعملات مختلفة: إذا كانت حزمتك تتعامل مع التواريخ أو الأوقات أو المعاملات المالية، فكن على دراية بالمناطق الزمنية والعملات المختلفة حول العالم. استخدم المكتبات وواجهات برمجة التطبيقات المناسبة للتعامل مع هذه التعقيدات بشكل صحيح.
• قدم رسائل خطأ واضحة: اكتب رسائل خطأ مفيدة تساعد المستخدمين على فهم الخطأ الذي حدث وكيفية إصلاحه. قم بترجمة رسائل الخطأ هذه إلى لغات مختلفة إن أمكن.
• فكر في إمكانية الوصول: ضع في اعتبارك المستخدمين ذوي الإعاقة عند تصميم واجهة حزمتك ووثائقها. اتبع إرشادات إمكانية الوصول لضمان أن تكون حزمتك قابلة للاستخدام من قبل الجميع.

مواضيع متقدمة

• حزم مساحة الاسم (Namespace packages): تسمح لك بتقسيم حزمة بايثون واحدة عبر عدة أدلة أو حتى عدة توزيعات.
• نقاط الدخول (Entry points): تسمح لك بتعريف دوال أو فئات يمكن استدعاؤها من حزم أخرى أو من سطر الأوامر.
• ملفات البيانات (Data files): تسمح لك بتضمين ملفات غير بايثون (مثل ملفات البيانات وملفات التكوين) في توزيعك.
• التبعيات الشرطية (Conditional dependencies): تسمح لك بتحديد التبعيات المطلوبة فقط في ظل ظروف معينة (على سبيل المثال، على نظام تشغيل معين).

الخاتمة

يعد توزيع حزمة بايثون الخاصة بك على PyPI طريقة رائعة لمشاركة عملك مع العالم والمساهمة في نظام بايثون البيئي. باتباع الخطوات وأفضل الممارسات الموضحة في هذا الدليل، يمكنك إنشاء ونشر حزم بايثون عالية الجودة سهلة التثبيت والاستخدام والصيانة. تذكر إعطاء الأولوية للوثائق الواضحة والاختبار الشامل وإدارة الإصدارات المتسقة لضمان نجاح حزمتك.